Fritz: All Fritz

home *** CD-ROM | disk | FTP | other *** search

/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / PROGMISC / FPCDOCS.LZH / TOOLS.DOC < prev next >

Wrap

Text File | 1988-06-01 | 16.2 KB | 455 lines

III. PROGRAMMING TOOLS 1. DUMP The dump utility gives you a formatted hex dump with the ascii text corresponding to the bytes on the right hand side of the screen. DUMP displays memory in the code segment, where code, strings, and other data are stored. XDUMP displays the list segment, where colon definitions are stored. YDUMP displays the header segment. These dump utilities are derived from the generic dump function LDUMP, which displays a range of memory from a memory segment whose segment address is stored in a variable DUMPSEG. DUMP, XDUMP, and YDUMP set DUMPSEG to the corresponding segment and then do LDUMP. One can store any segment address into DUMPSEG and use LDUMP to display that part of the memory, the dump segment, up to 64K bytes. LDUMP does not change DUMPSEG but DUMP, XDUMP, and YDUMP do change DUMPSEG to cs:, xs:, and ys:. Their behavior takes a little bit of getting use to, but they allow you to navigate through the entire segmented memory space. DUMPC@L fetches a byte in the segment specified by DUMPSEG. DU displays 64 bytes in the dump segment and increment the memory address by 64 so that you can continue dumping the next 64 bytes with another DU. 2. THE DEBUGGER The debugger is very similar to the F83 debugger. Some features have been added to enhance its operation. The decompiled source for the current definition being debugged is displayed while debugging. A typical command sequence might be as follows: DEBUG WORDS <enter> specify WORDS to be debugged as soon as it is executed. or DBG WORDS <enter> debug WORDS right now. Once in the debugger, you will be shown a display similar to the following: 17469 INWFLG ?> _ At this point, pressing return will cause the word INWFLG to be executed, and the debugger will print the stack after execution, and step to the next word in the list and wait for a command. Notice the fields in the above example. The number on the left is the address in memory where the debugger is currently working. The next word INWFLG is the word the debugger is about to execute. The next symbol "?>" is a marker pointing to what will be the printed stack contents after we press <enter>. The question mark symbol is the command we must press to see the command list for the debugger. If we press that now, we will see: C-cont, F-forth, Q-quit, N-nest, U-unnest: These are the commands you can use in the debugger. Their functions are as follows: C-cont Trace continuously until a key is pressed. F-forth Allow entry of Forth command lines until <enter> is pressed on an empty line. Q-quit Quit the debugger, and unpatch next. N-nest Nest into the ":" definition we were about to execute. Only works on ":" definitions, and deferred words. U-unnest Unnest the current ":" definition being debugged. Re-enters the debugger on the next higher level. You will have noticed that the upper portion of the screen is filled with the source for the word you are currently debugging. This is to make it easier to follow the debug process. You may want to turn off the source display, if it interferes with your the debuging process. The words to control this are: SRCOFF turn off the source display SRCON turn on the source display The default state is ON. DEBUG only sets the debugger up to debug a word. The debugging process does not start until the word is executed. A new debugging command DBG is added, which caused the following word to be executed and debugged immediately. The command sequence is: DBG <word_name> <enter> It is much easier to use and makes much of the intricate behavior of the F83 DEBUG transparent to the user. 3. CONSTANTS AS VARIABLES "Constants aren't; variables won't". A set of operators has been included for manipulating constants. Since constants are faster at run time than variables, performance in critical operations can take advantage of these. They may also provide a somewhat more readable source. Here is a list of them: =: value =: constant-name assign value to constant !> value !> constant-name assign value into constant-name @> @> constant-name ( --- n1 ) returns contants of its BODY. +!> value +!> constant-name increment constant-name by value incr> incr> constant-name increment constant-name by one decr> decr> constant-name decrement constant-name by one These operators are written in assembly, so they will be very fast. 4. HELP SEE WORDS' VIEW? F-PC provides the standard F83 decompiler, called SEE. SEE has been modified to display a decompiled source that is in most cases very similar to the original source on disk. VIEW behaves identically as that in F83. It opens the .SEQ file in which a word is defined and displays 16 lines of source code from the beginning of the definition. You can use the ED command to enter the editor and exploring the source code before or after this definition. Alternatively, you can use the B or N commands to examine the source one screen at a time without leaving F-PC even temporarily. HELP is a new function added in F-PC, which opens the companion .HLP file to the .SEQ file in which a word is defined and displays the help messages associated with the word. It assumes that the help file exists; otherwise, a file error message will be displayed. WORDS behaves identically as WORDS in F83 when used normally to display the names of definitions in the CONTEXT vocabulary. It is enhanced in F-PC such that if the string following it is not a valid name in the CONTEXT vocabulary, it will use the string as a substring pattern and prints the names of all definitions in all vocabularies, whose name contains the substring. The special string '*.*' given after WORDS causes all words in all vocabularies to be displayed. 5. DATE AND TIME A complete set of time and date manipulation words has been provided in F-PC. They call appropriate DOS service functions to produce the needed services. The words for getting and setting the date and time are as follows: GETDATE ( --- d1 ) Return d1 the 32bit binary date from the operating system. SETDATE ( d1 --- ) Given the binary date d1, set the system clock to that date. Bytes in d1 are arranged as year/month/day/day-of-week. GETTIME ( --- d1 ) Return d1 with bytes arranged in the order hr/min/sec/100th-sec from the operating system. SETTIME ( d1 --- ) Given the binary time d1, set the system clock to that time. .DATE ( --- ) Print to the screen, the current date, in the format MM/DD/YY, where MM is month, DD is day, and YY is year. .TIME ( --- ) Print to the screen, the current time, in the format HH:MM:SS.HR, where HH is hours, MM is minutes, ss is seconds, and HR is hundredths of a second. A special word set is defined in F-PC for measuring elapsed time for real time experiments and for program characterization. TIMER ( words --- ) TIMER performs the Forth words following on the same command line, and when they finish execution, TIMER prints the elapsed time required for their execution. TIME-RESET ( --- ) Reset the accumulated time value in the double variable STIME to zero, in effect resetting the current elapsed time to zero. This word is used at the beginning of a sequence of operations you want to time. The word .ELAPSED is used at the end of the operations to print the elapsed time since the last TIME-RESET. .ELAPSED ( --- ) Print the elapsed time since the last TIME-RESET was performed. TENTHS ( tenths_ofa_second --- ) SECONDS ( seconds --- ) MINUTES ( minutes --- ) HOURS ( hours --- ) Time delay words use the system time function to obtain very accurate time delays. Background processing continues, as pause is called in the wait loop. Another deferred word, PAUSE-FUNC, is also in the loop, which can be re deferred to perform any function you want done while the delay is occurring. 6. COMMENTS All comment words in F83, like (, .(, (S, \, \S are preserved and they behave identically in F-PC. However, a file in F-PC is similar to a block in F83 and \S stops the compilation of the rest of the file. To accommodate documentation which spans over many lines, additional comment words are defined in F-PC. Multiple line comment in F-PC starts with COMMENT: and terminates at COMMEMT; . It looks like: COMMENT: <text> <more text> ... <even more text> COMMENT; To print multiple line comments during compiling, .COMMENT: ( lines_of_text --- ) ... COMMENT; Starts a group of lines, that are to be printed to the terminal, until a terminating "COMMENT;" is found. 7. SCREEN CONTROL WORDS IN F-PC F-PC allows you to control the CRT screen to generate very fancy text displays. Most of these screen control words call DOS video service to change the character attributes on characters emitted to the screen. FAST ( --- ) Select the Fast screen output routines that are very hardware dependant. Much faster than BDOS, but requires VERY compatible hardware. SLOW ( --- ) Select the SLOW screen output routines, these routines use BDOS for screen output, and are less hardware dependant than FAST. >UL ( --- ) underline >REV ( --- ) reverse >BOLD ( --- ) bold >BOLDUL ( --- ) bold underline >BOLDBLNK ( --- ) bold blink >REVBLNK ( --- ) reverse blink >NORM ( --- ) normal video Select the various types of attributes available on the monochrome monitor. COLOR support has been added. F-PC as delivered is configured for Monochrome, but will work on a color monitor. The INSTALL process will automatically install color support if a color board is being used during installation. >FG ( n1 --- ) foreground >BG ( n1 --- ) background Words from the COLOR.SEQ file that allow setting the foreground and background colors on a color monitor: >ATTRIB1 ( --- ) >ATTRIB2 ( --- ) >ATTRIB3 ( --- ) >ATTRIB4 ( --- ) Deferred words to allow selection of the various display attributes for the current display board. They default to the following attributes for Monochrome and Color. MONOCHROME COLOR word bgrnd fgrnd --------------------------------------------- >ATTRIB1 UNDERLINE BLUE GREEN >ATTRIB2 BOLD UNDERLINE RED WHITE >ATTRIB3 BOLD BLUE WHITE >ATTRIB4 REVERSE RED WHITE These values can be changed by changing either COLOR.SEQ, or MONOCROM.SEQ and re-installing the system with INSTALL.BAT. SAVESCR ( --- ) save screen RESTSCR ( --- ) restore screen These words give you the ability to save the screen contents and later restore the screen to its original appearance in a simple way. SAVESCR may be used and nested up to three times before RESTSCR needs to be done. That is, three screens can be saved and sequentially restored. 8. COMPILATION CONTROL WORDS To load a source file, the most convenient way is to use the command FLOAD: FLOAD <file_name> <enter> will open the file and compile the source code start at the beginning. After the file is compiled, FLOAD closes the file so that other files can be loaded. If a file is openned by the editor, OK <enter> compile the currently open file, starting at the beginning, and continuing through the end of the file or until an error is encountered. <line_number> LOAD <enter> Start loading the current file starting at the <line_number> specified. Loads through the end of the file or until an error is encountered. A tool of the type used in F83X has been added, called ?NEEDS. This word when followed by a filename will conditionally load the specified file if the file has not already been loaded. Be sure to include the filename extension. Another word ?UNWANTED, when followed by a filename, aborts with an error if the Unwanted file has already been loaded. The word #IF has been added, which accepts a boolean flag, and determines if the lines following #IF are loaded up until the #ENDIF. A TRUE flag causes the lines to be loaded. A FALSE flag causes the lines to be skipped. TRUE #IF .( This message will be printed.) #ENDIF 9. PRINTING SOURCE FILES IN F-PC. Files can of course be printed while in the editor, but you can also print files from the Forth command line as follows: OPEN <filename> <enter> open a file LISTING <enter> print the file The print format is the same as the default format for the editor. Another command which combines the two commands above is as follows: FPRINT <filespec> <enter> Literally opens the file and performs a LISTING. Wildcard characters can be used in the file specification so that many files are printed with a single FPRINT command. INDEX <filespec> <enter> behaves similarly to FPRINT. However, it prints only the first line of each file specified. 10. GLOBAL SEARCH One of the neat additions to F-PC is EDITALL. EDITALL is used as follows: EDITALL <string> <filespecs>... <enter> All filespecs are searched for string, if string is found, the the editor is entered on that line of the file, ready for you to perform an edit or replace on the string. Only the first occurance of string is located, so repeated Alt-F6 commands can locate additional occurances of string in the file. Shift-F8 Replace all can also be used while in a file to replace all occurances of string with another string. When you are done editing, press ESC, to terminate edit, and the search will continue through the filespecs specified for additional occurances of string, until all files have been found that contain string. This has been very valuble to me in maintaining the system, and making global changes to all occurances of a Forth word name. FLOOK is another interesting addition to F-PC. It performs similarly to EDITALL in searching a word through many files, but just displays the file and line number of all occurances found.